<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Loop (registry)</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Loop (registry)</h1>

<p>Retrieves the contents of the specified registry subkey, one item at a time.</p>

<pre class="Syntax">Loop, Reg, RootKey[\Key, Mode]  <em>; v1.1.21+ (recommended)</em></pre>
<pre class="Syntax">Loop, RootKey [, Key, IncludeSubkeys?, Recurse?]</pre>
<h3>Parameters</h3>
<dl>

  <dt>Reg <span class="ver">[v1.1.21+]</span></dt>
  <dd><p>The literal word <code>Reg</code> (case-insensitive). This cannot be a variable or expression. If this keyword is present, <em>Key</em> must be separated from <em>RootKey</em> by a slash instead of a comma, and both can be contained within a single variable. For example, <code>Loop, Reg, HKLM\Software</code> or <code>Loop, Reg, %FullPathOfKey%</code>.</p></dd>

  <dt>RootKey</dt>
  <dd><p>Must be either HKEY_LOCAL_MACHINE (or HKLM), HKEY_USERS (or HKU), HKEY_CURRENT_USER (or HKCU), HKEY_CLASSES_ROOT (or HKCR), or HKEY_CURRENT_CONFIG (or HKCC).</p>
      <p>To access a remote registry, prepend the computer name and a colon, as in this example: \\workstation01:HKEY_LOCAL_MACHINE</p></dd>

  <dt>Key</dt>
  <dd><p>The name of the key (e.g. Software\SomeApplication). If blank or omitted, the contents of <em>RootKey</em> will be retrieved.</p></dd>
  
  <dt>Mode <span class="ver">[v1.1.21+]</span></dt>
  <dd><p>Zero or more of the following letters:</p>
    <p><code>K</code>: Include keys.<br>
    <code>V</code>: Include values. Values are also included if both K and V are omitted.<br>
    <code>R</code>: Recurse into subkeys. If R is omitted, keys and values within subkeys of <em>Key</em> are not included.</p>
  </dd>

  <dt>IncludeSubkeys?</dt>
  <dd><p>0 (default) Subkeys contained within <em>Key</em> are not retrieved (only the values).<br>
  1 All values and subkeys are retrieved.<br>
  2 Only the subkeys are retrieved (not the values).</p></dd>

  <dt>Recurse?</dt>
  <dd>0 (default) Subkeys are not recursed into.<br>
1 Subkeys are recursed into, so that all values and subkeys contained therein are retrieved.</dd>

</dl>

<h3>Remarks</h3>
<p>A registry-loop is useful when you want to operate on a collection registry values or subkeys, one at a time. The values and subkeys are retrieved in reverse order (bottom to top) so that <a href="RegDelete.htm">RegDelete</a> can be used inside the loop without disrupting the loop.</p>
<p id="vars">The following variables exist within any registry-loop. If an inner registry-loop is enclosed by an outer registry-loop, the innermost loop's registry item will take precedence:</p>
<table class="info">
  <tr>
    <td>A_LoopRegName</td>
    <td>Name of the currently retrieved item, which can be either a value name or the name of a subkey. Value names displayed by Windows RegEdit as &quot;(Default)&quot; will be retrieved if a value has been assigned to them, but A_LoopRegName will be blank for them.</td>
  </tr>
  <tr>
    <td>A_LoopRegType</td>
    <td>The type of the currently retrieved item, which is one of the following words: KEY (i.e. the currently retrieved item is a subkey not a value), REG_SZ, REG_EXPAND_SZ, REG_MULTI_SZ, REG_DWORD, REG_QWORD, REG_BINARY, REG_LINK, REG_RESOURCE_LIST, REG_FULL_RESOURCE_DESCRIPTOR, REG_RESOURCE_REQUIREMENTS_LIST, REG_DWORD_BIG_ENDIAN (probably rare on most Windows hardware). It will be empty if the currently retrieved item is of an unknown type.</td>
  </tr>
  <tr>
    <td>A_LoopRegKey</td>
    <td>The name of the root key being accessed  (HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_CURRENT_USER, HKEY_CLASSES_ROOT, or HKEY_CURRENT_CONFIG). For remote registry access, this value will <strong>not</strong> include the computer name.</td>
  </tr>
  <tr>
    <td>A_LoopRegSubKey</td>
    <td>Name of the current SubKey. This will be the same as the <em>Key</em> parameter unless the <em>Recurse</em> parameter is being used to recursively explore other subkeys. In that case, it will be the full path of the currently retrieved item, not including the root key. For example: Software\SomeApplication\My SubKey</td>
  </tr>
  <tr>
    <td>A_LoopRegTimeModified</td>
    <td>The time the current subkey or any of its values was last modified. Format <a href="FileSetTime.htm">YYYYMMDDHH24MISS</a>. This variable will be empty if the currently retrieved item is not a subkey (i.e. <em>A_LoopRegType</em> is not the word KEY).</td>
  </tr>
</table>
<p>When used inside a registry-loop, the following commands can be used in a simplified way to indicate that the currently retrieved item should be operated upon:</p>
<table class="info">
  <tr>
    <td width="21%"><a href="RegRead.htm">RegRead</a>, OutputVar</td>
    <td width="79%">Reads the current item. If the current item is a key, ErrorLevel will be set to 1 and <em>OutputVar</em> will be made empty.</td>
  </tr>
  <tr>
    <td><a href="RegWrite.htm">RegWrite</a> [, Value]</td>
    <td>Writes to the current item. If <em>Value</em> is omitted, the item will be made 0 or blank depending on its type. If the current item is a key, ErrorLevel will be set to 1 and there will be no other effect.</td>
  </tr>
  <tr>
    <td><a href="RegDelete.htm">RegDelete</a></td>
    <td>Deletes the current item. If the current item is a key, it will be deleted along with any subkeys and values it contains.</td>
  </tr>
</table>
<p>When accessing a remote registry (via the <em>RootKey</em> parameter described above), the following notes apply:</p>
<ul>
  <li>The target machine must be running the Remote Registry service.</li>
  <li>Access to a remote registry may fail if the target computer is not in the same domain as yours or the local or remote username  lacks sufficient permissions (however, see below for possible workarounds).</li>
  <li>Depending on your username's domain, workgroup, and/or permissions, you may have to connect to a shared device, such as by mapping a drive, prior to attempting remote registry access. Making such a connection -- using a remote username and password that has permission to access or edit the registry -- may as a side-effect enable remote registry access.</li>
  <li>If you're already connected to the target computer as a different user (for example, a mapped drive via user Guest), you may have to terminate that connection to allow the remote registry feature to reconnect and re-authenticate you as your own currently logged-on username.</li>
  <li>For Windows Server 2003 and Windows XP Professional, MSDN states: &quot;If the [registry server] computer is joined to a workgroup and the <em>Force network logons using local accounts to authenticate as Guest</em> policy is enabled, the function fails. Note that this policy is enabled by default if the computer is joined to a workgroup.&quot;</li>
  <li>For Windows XP Home Edition, MSDN states that &quot;this function always fails&quot;. Home Edition lacks both the registry server and client, though the client can be extracted from one of the OS cab files.</li>
</ul>
<p>See <a href="Loop.htm">Loop</a> for information about <a href="Block.htm">Blocks</a>, <a href="Break.htm">Break</a>, <a href="Continue.htm">Continue</a>, and the A_Index variable (which exists in every type of loop).</p>
<h3>Related</h3>
<p><a href="Loop.htm">Loop</a>, <a href="Break.htm">Break</a>, <a href="Continue.htm">Continue</a>, <a href="Block.htm">Blocks</a>, <a href="RegRead.htm">RegRead</a>, <a href="RegWrite.htm">RegWrite</a>, <a href="RegDelete.htm">RegDelete</a>, <a href="SetRegView.htm">SetRegView</a></p>

<h3>Examples</h3>
<pre class="NoIndent"><em>; Example: Delete Internet Explorer's history of URLs typed by the user:</em>
Loop, HKEY_CURRENT_USER, Software\Microsoft\Internet Explorer\TypedURLs
    RegDelete</pre>
<p>&nbsp;</p>
<pre class="NoIndent"><em>; Example: A working test script:</em>
Loop, Reg, HKEY_CURRENT_USER\Software\Microsoft\Windows, KVR
{
    if a_LoopRegType = key
        value =
    else
    {
        RegRead, value
        if ErrorLevel
            value = *error*
    }
    MsgBox, 4, , %a_LoopRegName% = %value% (%a_LoopRegType%)`n`nContinue?
    IfMsgBox, NO, break
}</pre>
<p>&nbsp;</p>
<pre class="NoIndent"><em>; Example: A working example to recursively search the entire
; registry for particular value(s).</em>
SetBatchLines -1  <em>; Makes searching occur at maximum speed.</em>
RegSearchTarget = Notepad  <em>; Tell the subroutine what to search for.</em>
Gosub, RegSearch
return

RegSearch:
ContinueRegSearch = y
Loop, Reg, HKEY_LOCAL_MACHINE, KVR
{
    Gosub, CheckThisRegItem
    if ContinueRegSearch = n <em>; It told us to stop.</em>
        return
}
Loop, Reg, HKEY_USERS, KVR
{
    Gosub, CheckThisRegItem
    if ContinueRegSearch = n <em>; It told us to stop.</em>
        return
}
Loop, Reg, HKEY_CURRENT_CONFIG, KVR
{
    Gosub, CheckThisRegItem
    if ContinueRegSearch = n <em>; It told us to stop.</em>
        return
}
<em>; Note: I believe HKEY_CURRENT_USER does not need to be searched if HKEY_USERS
; is being searched.  The same might also be true for HKEY_CLASSES_ROOT if
; HKEY_LOCAL_MACHINE is being searched.</em>
return

CheckThisRegItem:
if A_LoopRegType = KEY  <em>; Remove these two lines if you want to check key names too.</em>
    return
RegRead, RegValue
if ErrorLevel
    return
IfInString, RegValue, %RegSearchTarget%
{
    MsgBox, 4, , The following match was found:`n%A_LoopRegKey%\%A_LoopRegSubKey%\%A_LoopRegName%`nValue = %RegValue%`n`nContinue?
    IfMsgBox, No
        ContinueRegSearch = n  <em>; Tell our caller to stop searching.</em>
}
return</pre>

</body>
</html>
